Back to Contents Previous Next
14. Sprite areas & Mouse pointers **
As was introduced in Section 2.12, in order to display/print sprites in a Wimp application they need to be loaded into memory somewhere - as opposed to being left in a file.
All the sprites we have used so far in our tutorial have been from a special area of memory called the ‘Wimp sprite pool’ which is loaded automatically on computer start-up.
We can add sprites to this pool using the Iconsprites
star command - as is usually done in the !Boot and !Run files of an application. However, this method is really only intended for sprites which are to be used by the Filer (e.g. application sprites for Filer windows, iconbar, pinboard, etc.) and we may wish to display other sprites in other circumstances. For example, sprites which are solely for use during the running of our application and which can be safely discarded again when we quit it.
To do this, Dr Wimp allows an application to create it’s own (’private’ or ‘user’) sprite areas - which are stored in the wimpslot, the memory used by the application. This has a speed advantage and also, when the application quits, all the memory is regained. We will use the phrase ‘user sprites’ to describe sprites that are held in such a sprite area.
Tutorial
We are going to put a sprite-file (holding a single sprite) into a ‘user sprite’ area by using the sequence described in detail in Section 2.12 for the loading of files into a memory block - here, specifically, the sprite-file case.
Then, rather than display the sprite from this sprite-file in a window, we going to combine two aspects by using the sprite to change the shape of the mouse pointer.
This will conveniently introduce the point that the mouse pointer is also simply a sprite, which can be changed.
So, starting with !MyApp as we left it in Section 2.10 (i.e. as in tutorial listing RI_07) copy the file “Sprites” from the Tutorials folder into the !MyApp directory. This spritefile holds a sprite called “ptr_hand” - a small shape of a hand.
Then, in the !RunImage listing, enter the following standard file-loading lines into PROCuser_initialise
:
size%=FNwimp_measurefile("<MyApp$Dir>.Sprites",0)
DIM sprites% size%
a%=FNwimp_loadsprites(“<MyApp$Dir>.Sprites”,sprites%,0)
As Section 2.12 explains, the first line measures the spritefile size; the second creates a corresponding memory block, called sprites%
here - and the last line loads the file into that block (with a%
being an arbitrary variable not being used elsewhere). sprites%
therefore becomes the handle of the loaded sprite-file.
Now let’s use the sprite in the sprite-file we have just loaded, and we will be introducing two new user-functions and one new wimp-function.
Whenever the pointer moves in and out of one of your application’s windows, the functions PROCuser_enteringwindow
()
and PROCuser_leavingwindow
()
are called automatically. They both have the single parameter window%
, which will contain the handle of the window concerned.
So, in PROCuser_enteringwindow
, add the following lines:
IF window%=main% THEN
PROCwimp_pointer(1,sprites%,“ptr_hand”)
ENDIF
And in PROCuser_leavingwindow
, add the following:
IF window%=main% THEN
PROCwimp_pointer(0,0,“”)
ENDIF
Run !MyApp and you should find that when you move the pointer over the main window, it turns into a hand and it changes back to the normal shape when you leave the window. (If you get a “No room for this DIM” error, you have not copied the file Sprites
to the !MyApp directory!)
The first parameter of PROCwimp_pointer(pointer%,spritearea%,pointer$)
tells DrWimp whether to use the Wimp’s default pointer (0), or a user-defined one (1).
The second parameter tells which sprite area is to be used, 0 for the Wimp sprite pool, or a handle for a ‘user sprite’ area.
The Wimp’s default pointer is held in the Wimp sprite pool, so when we want to use the default pointer shape both the first and second parameters should be 0.
However, if we wish to use a sprite from a ‘user sprite’ area instead, the first two parameters should be, respectively, 1 and the private sprite area handle holding the sprite - which, here, is the handle sprites%
.
The last parameter is the name of the sprite to use and it only has relevance if the first parameter is set to 1, in which case we put the name of the sprite i.e. “ptr_hand”
, as in the first case above. If the first parameter is 0 (i.e. we want to use the Wimp’s default pointer) then the third parameter will be ignored - but there is still a need to put something there and a null string, as in the second case above, is a good idea.)
[Your !RunImage listing should now look like listing RI_08 in Tutor1
(apart from the REM
lines, perhaps). Do not destroy it as the next section - Section 2.15 - uses it briefly.]
One of the most frequent uses of ‘user sprites’ is so that they can be displayed in a Wimp program and/or printed from it. Sections 2.19 and 2.22 are devoted to that topic.
Also, if you recall the early part of Section 2.3 where we introduced the loading of a window template, ‘user sprite’ areas can be used in icons in the window design provided that they are created prior to the window template loading. In that case, the ‘user sprite’ area handle is put into the final parameter of FNwimp_loadwindow()
- as indicated in that earlier reference.
The number of sprites in a spritefile can be obtained with FNwimp_countsprites
, and the names of sprites in a spritefile can be found with FNwimp_getspritename
.
Change of pointer sprite using icon ‘validation string’
It is convenient to end this section with a mention of a related matter. You may have noticed that, with some writable icons, when the pointer is over the icon it changes into a pointer looking like a caret. This is effected via the P-command of the icon’s ‘validation string’ - see Section 2.28 - which simply changes the sprite used for the mouse pointer as it passes over the icon.
For example, in the validation field of a writable icon you will probably see:
R7;Pptr_write
This particular validation string shows two Commands: an R-command and a P-command, separated by a semi-colon. The P-command specifies a sprite (which must be in the Wimp’s sprite pool) to be used for the pointer when over the sprite - and “ptr_write” is the name of the sprite. This sprite is a thin vertical red line - the caret. (R7 describes the particular border given to the icon.)
You will also often see other pointer shapes with other types of icons e.g. a menu shape over menu icons, and their validation strings will show a corresponding sprite from the Wimp sprite pool.
Top of page Back to Contents Previous Next